# eric7.MicroPython.Devices.EspDevices

Module implementing the device interface class for ESP32 and ESP8266 based boards.

### Global Attributes

None

### Classes

EspDevice | Class implementing the device for ESP32 and ESP8266 based boards.

### Functions

createDevice | Function to instantiate a MicroPython device object.
eraseFlash | Slot to erase the device flash memory.
flashAddonFirmware | Slot to flash some additional firmware images.
flashPythonFirmware | Slot to flash a MicroPython firmware to the device.

## EspDevice

Class implementing the device for ESP32 and ESP8266 based boards.

### Derived from

BaseDevice

### Class Attributes

None

### Class Methods

None

### Methods

EspDevice | Constructor
__backupFlash | Private slot to backup the currently flashed firmware.
__createCpyDevice | Private method to create a CircuitPython device interface.
__createEsp32Submenu | Private method to create the ESP32 submenu.
__eraseFlash | Private slot to erase the device flash memory.
__firmwareVersionResponse | Private slot handling the response of the latest version request.
__flashAddons | Private slot to flash some additional firmware images.
__flashMicroPython | Private slot to flash a MicroPython firmware to the device.
__installEspTool | Private slot to install the esptool package via pip.
__resetCountry | Private slot to reset the country of the connected ESP32 device.
__resetDevice | Private slot to reset the connected device.
__restoreFlash | Private slot to restore a previously saved firmware.
__setCountry | Private slot to configure the country of the connected ESP32 device.
__showChipID | Private slot to show the ID of the ESP chip.
__showFirmwareVersions | Private slot to show the firmware version of the connected device and the available firmware version.
__showFlashID | Private slot to show the ID of the ESP flash chip.
__showMACAddress | Private slot to show the MAC address of the ESP chip.
__showSecurityInfo | Private slot to show some security related information of the ESP chip.
_getSetTimeCode | Protected method to get the device code to set the time.
activateBluetoothInterface | Public method to activate the Bluetooth interface.
addDeviceMenuEntries | Public method to add device specific entries to the given menu.
addDeviceWifiEntries | Public method to add device specific entries to the given menu.
canRunScript | Public method to determine, if a script can be executed.
canStartFileManager | Public method to determine, if a File Manager can be started.
canStartPlotter | Public method to determine, if a Plotter can be started.
canStartRepl | Public method to determine, if a REPL can be started.
checkInternet | Public method to check, if the internet can be reached.
connectWifi | Public method to connect a device to a WiFi network.
deactivateBluetoothInterface | Public method to deactivate the Bluetooth interface.
deactivateInterface | Public method to deactivate a given WiFi interface of the connected device.
deviceName | Public method to get the name of the device.
disableWebrepl | Public method to write the given WebREPL password to the connected device and modify the start script to start the WebREPL server.
disconnectWifi | Public method to disconnect a device from the WiFi network.
enableWebrepl | Public method to write the given WebREPL password to the connected device and modify the start script to start the WebREPL server.
forceInterrupt | Public method to determine the need for an interrupt when opening the serial connection.
getBluetoothStatus | Public method to get Bluetooth status data of the connected board.
getConnectedClients | Public method to get a list of connected clients.
getDeviceScan | Public method to perform a Bluetooth device scan.
getDocumentationUrl | Public method to get the device documentation URL.
getFirmwareUrl | Public method to get the device firmware download URL.
getWifiData | Public method to get data related to the current WiFi status.
hasBluetooth | Public method to check the availability of Bluetooth.
hasFlashMenuEntry | Public method to check, if the device has its own flash menu entry.
hasNetworkTime | Public method to check the availability of network time functions.
hasWifi | Public method to check the availability of WiFi.
hasWifiCountry | Public method to check, if the device has support to set the WiFi country.
isWifiApConnected | Public method to check the WiFi connection status as access point.
isWifiClientConnected | Public method to check the WiFi connection status as client.
removeCredentials | Public method to remove the saved credentials from the connected device.
runScript | Public method to run the given Python script.
scanNetworks | Public method to scan for available WiFi networks.
setButtons | Public method to enable the supported action buttons.
setConnected | Public method to set the connection state.
setNetworkTime | Public method to set the time to the network time retrieved from an NTP server.
startAccessPoint | Public method to start the access point interface.
stopAccessPoint | Public method to stop the access point interface.
supportsDeviceScan | Public method to indicate, that the Bluetooth implementation supports scanning for devices.
writeCredentials | Public method to write the given credentials to the connected device and modify the start script to connect automatically.

### Static Methods

None

#### EspDevice (Constructor)

EspDevice(microPythonWidget, deviceType, parent=None)

Constructor

microPythonWidget (MicroPythonWidget)
  reference to the main MicroPython widget
deviceType (str)
  device type assigned to this device interface
parent (QObject)
  reference to the parent object

#### EspDevice.__backupFlash

__backupFlash()

Private slot to backup the currently flashed firmware.

#### EspDevice.__createCpyDevice

__createCpyDevice()

Private method to create a CircuitPython device interface.

#### EspDevice.__createEsp32Submenu

__createEsp32Submenu()

Private method to create the ESP32 submenu.

#### EspDevice.__eraseFlash

__eraseFlash()

Private slot to erase the device flash memory.

#### EspDevice.__firmwareVersionResponse

__firmwareVersionResponse(reply)

Private slot handling the response of the latest version request.

reply (QNetworkReply)
  reference to the reply object

#### EspDevice.__flashAddons

__flashAddons()

Private slot to flash some additional firmware images.

#### EspDevice.__flashMicroPython

__flashMicroPython()

Private slot to flash a MicroPython firmware to the device.

#### EspDevice.__installEspTool

__installEspTool()

Private slot to install the esptool package via pip.

#### EspDevice.__resetCountry

__resetCountry()

Private slot to reset the country of the connected ESP32 device.

The country is the two-letter ISO 3166-1 Alpha-2 country code. This method resets it to the default code 'XX' representing the "worldwide" region.

#### EspDevice.__resetDevice

__resetDevice()

Private slot to reset the connected device.

#### EspDevice.__restoreFlash

__restoreFlash()

Private slot to restore a previously saved firmware.

#### EspDevice.__setCountry

__setCountry()

Private slot to configure the country of the connected ESP32 device.

The country is the two-letter ISO 3166-1 Alpha-2 country code.

#### EspDevice.__showChipID

__showChipID()

Private slot to show the ID of the ESP chip.

#### EspDevice.__showFirmwareVersions

__showFirmwareVersions()

Private slot to show the firmware version of the connected device and the available firmware version.

#### EspDevice.__showFlashID

__showFlashID()

Private slot to show the ID of the ESP flash chip.

#### EspDevice.__showMACAddress

__showMACAddress()

Private slot to show the MAC address of the ESP chip.

#### EspDevice.__showSecurityInfo

__showSecurityInfo()

Private slot to show some security related information of the ESP chip.

#### EspDevice._getSetTimeCode

_getSetTimeCode()

Protected method to get the device code to set the time.

Note: This method must be implemented in the various device specific subclasses.

Return:
  code to be executed on the connected device to set the time

Return Type:
  str

#### EspDevice.activateBluetoothInterface

activateBluetoothInterface()

Public method to activate the Bluetooth interface.

Return:
  flag indicating the new state of the Bluetooth interface

Return Type:
  bool

Raises OSError:
  raised to indicate an issue with the device

#### EspDevice.addDeviceMenuEntries

addDeviceMenuEntries(menu)

Public method to add device specific entries to the given menu.

menu (QMenu)
  reference to the context menu

#### EspDevice.addDeviceWifiEntries

addDeviceWifiEntries(menu)

Public method to add device specific entries to the given menu.

menu (QMenu)
  reference to the context menu

#### EspDevice.canRunScript

canRunScript()

Public method to determine, if a script can be executed.

Return:
  tuple containing a flag indicating it is safe to start a Plotter and a reason why it cannot.

Return Type:
  tuple of (bool, str)

#### EspDevice.canStartFileManager

canStartFileManager()

Public method to determine, if a File Manager can be started.

Return:
  tuple containing a flag indicating it is safe to start a File Manager and a reason why it cannot.

Return Type:
  tuple of (bool, str)

#### EspDevice.canStartPlotter

canStartPlotter()

Public method to determine, if a Plotter can be started.

Return:
  tuple containing a flag indicating it is safe to start a Plotter and a reason why it cannot.

Return Type:
  tuple of (bool, str)

#### EspDevice.canStartRepl

canStartRepl()

Public method to determine, if a REPL can be started.

Return:
  tuple containing a flag indicating it is safe to start a REPL and a reason why it cannot.

Return Type:
  tuple of (bool, str)

#### EspDevice.checkInternet

checkInternet()

Public method to check, if the internet can be reached.

Return:
  tuple containing a flag indicating reachability and an error string

Return Type:
  tuple of (bool, str)

#### EspDevice.connectWifi

connectWifi(ssid, password, hostname, country="")

Public method to connect a device to a WiFi network.

ssid (str)
  name (SSID) of the WiFi network
password (str)
  password needed to connect
hostname (str)
  host name of the device
country (str)
  WiFi country code

Return:
  tuple containing the connection status and an error string

Return Type:
  tuple of (bool, str)

#### EspDevice.deactivateBluetoothInterface

deactivateBluetoothInterface()

Public method to deactivate the Bluetooth interface.

Return:
  flag indicating the new state of the Bluetooth interface

Return Type:
  bool

Raises OSError:
  raised to indicate an issue with the device

#### EspDevice.deactivateInterface

deactivateInterface(interface)

Public method to deactivate a given WiFi interface of the connected device.

interface (str)
  designation of the interface to be deactivated (one of 'AP' or 'STA')

Return:
  tuple containg a flag indicating success and an error message

Return Type:
  tuple of (bool, str)

Raises ValueError:
  raised to indicate a wrong value for the interface type

#### EspDevice.deviceName

deviceName()

Public method to get the name of the device.

Return:
  name of the device

Return Type:
  str

#### EspDevice.disableWebrepl

disableWebrepl()

Public method to write the given WebREPL password to the connected device and modify the start script to start the WebREPL server.

Return:
  tuple containing a flag indicating success and an error message

Return Type:
  tuple of (bool, str)

#### EspDevice.disconnectWifi

disconnectWifi()

Public method to disconnect a device from the WiFi network.

Return:
  tuple containing a flag indicating success and an error string

Return Type:
  tuple of (bool, str)

#### EspDevice.enableWebrepl

enableWebrepl(password)

Public method to write the given WebREPL password to the connected device and modify the start script to start the WebREPL server.

password (str)
  password needed to authenticate

Return:
  tuple containing a flag indicating success and an error message

Return Type:
  tuple of (bool, str)

#### EspDevice.forceInterrupt

forceInterrupt()

Public method to determine the need for an interrupt when opening the serial connection.

Return:
  flag indicating an interrupt is needed

Return Type:
  bool

#### EspDevice.getBluetoothStatus

getBluetoothStatus()

Public method to get Bluetooth status data of the connected board.

Return:
  list of tuples containing the translated status data label and the associated value

Return Type:
  list of tuples of (str, str)

Raises OSError:
  raised to indicate an issue with the device

#### EspDevice.getConnectedClients

getConnectedClients()

Public method to get a list of connected clients.

Return:
  a tuple containing a list of tuples containing the client MAC-Address and the RSSI (if supported and available) and an error message

Return Type:
  tuple of ([(bytes, int)], str)

#### EspDevice.getDeviceScan

getDeviceScan(timeout=10)

Public method to perform a Bluetooth device scan.

timeout (int (optional))
  duration of the device scan in seconds (defaults to 10)

Return:
  tuple containing a dictionary with the scan results and an error string

Return Type:
  tuple of (dict, str)

#### EspDevice.getDocumentationUrl

getDocumentationUrl()

Public method to get the device documentation URL.

Return:
  documentation URL of the device

Return Type:
  str

#### EspDevice.getFirmwareUrl

getFirmwareUrl()

Public method to get the device firmware download URL.

Return:
  firmware download URL of the device

Return Type:
  str

#### EspDevice.getWifiData

getWifiData()

Public method to get data related to the current WiFi status.

Return:
  tuple of three dictionaries containing the WiFi status data for the WiFi client, access point and overall data

Return Type:
  tuple of (dict, dict, dict)

Raises OSError:
  raised to indicate an issue with the device

#### EspDevice.hasBluetooth

hasBluetooth()

Public method to check the availability of Bluetooth.

Return:
  flag indicating the availability of Bluetooth

Return Type:
  bool

Raises OSError:
  raised to indicate an issue with the device

#### EspDevice.hasFlashMenuEntry

hasFlashMenuEntry()

Public method to check, if the device has its own flash menu entry.

Return:
  flag indicating a specific flash menu entry

Return Type:
  bool

#### EspDevice.hasNetworkTime

hasNetworkTime()

Public method to check the availability of network time functions.

Return:
  flag indicating the availability of network time functions

Return Type:
  bool

Raises OSError:
  raised to indicate an issue with the device

#### EspDevice.hasWifi

hasWifi()

Public method to check the availability of WiFi.

Return:
  tuple containing a flag indicating the availability of WiFi and the WiFi type (esp32)

Return Type:
  tuple of (bool, str)

#### EspDevice.hasWifiCountry

hasWifiCountry()

Public method to check, if the device has support to set the WiFi country.

Return:
  flag indicating the support of WiFi country

Return Type:
  bool

#### EspDevice.isWifiApConnected

isWifiApConnected()

Public method to check the WiFi connection status as access point.

Return:
  flag indicating the WiFi connection status

Return Type:
  bool

#### EspDevice.isWifiClientConnected

isWifiClientConnected()

Public method to check the WiFi connection status as client.

Return:
  flag indicating the WiFi connection status

Return Type:
  bool

#### EspDevice.removeCredentials

removeCredentials()

Public method to remove the saved credentials from the connected device.

Return:
  tuple containing a flag indicating success and an error message

Return Type:
  tuple of (bool, str)

#### EspDevice.runScript

runScript(script)

Public method to run the given Python script.

script (str)
  script to be executed

#### EspDevice.scanNetworks

scanNetworks()

Public method to scan for available WiFi networks.

Return:
  tuple containing the list of available networks as a tuple of 'Name', 'MAC-Address', 'channel', 'RSSI' and 'security' and an error string

Return Type:
  tuple of (list of tuple of (str, str, int, int, str), str)

#### EspDevice.setButtons

setButtons()

Public method to enable the supported action buttons.

#### EspDevice.setConnected

setConnected(connected)

Public method to set the connection state.

Note: This method can be overwritten to perform actions upon connect or disconnect of the device.

connected (bool)
  connection state

#### EspDevice.setNetworkTime

setNetworkTime(server="0.pool.ntp.org", tzOffset=0, timeout=10)

Public method to set the time to the network time retrieved from an NTP server.

server (str (optional))
  name of the NTP server to get the network time from (defaults to "0.pool.ntp.org")
tzOffset (int (optional))
  offset with respect to UTC (defaults to 0)
timeout (int)
  maximum time to wait for a server response in seconds (defaults to 10)

Return:
  tuple containing a flag indicating success and an error string

Return Type:
  tuple of (bool, str)

#### EspDevice.startAccessPoint

startAccessPoint(ssid, security=None, password=None, hostname=None, ifconfig=None, )

Public method to start the access point interface.

ssid (str)
  SSID of the access point
security (str (optional))
  security mode (defaults to None) (unused)
password (str (optional))
  password (defaults to None)
hostname (str (optional))
  host name of the device (defaults to None)
ifconfig (tuple of (str, str, str, str))
  IPv4 configuration for the access point if not default (IPv4 address, netmask, gateway address, DNS server address)

Return:
  tuple containing a flag indicating success and an error message

Return Type:
  tuple of (bool, str)

#### EspDevice.stopAccessPoint

stopAccessPoint()

Public method to stop the access point interface.

Return:
  tuple containg a flag indicating success and an error message

Return Type:
  tuple of (bool, str)

#### EspDevice.supportsDeviceScan

supportsDeviceScan()

Public method to indicate, that the Bluetooth implementation supports scanning for devices.

Return:
  flag indicating that the scanning function is supported

Return Type:
  bool

#### EspDevice.writeCredentials

writeCredentials(ssid, password, hostname, country)

Public method to write the given credentials to the connected device and modify the start script to connect automatically.

ssid (str)
  SSID of the network to connect to
password (str)
  password needed to authenticate
hostname (str)
  host name of the device
country (str)
  WiFi country code

Return:
  tuple containing a flag indicating success and an error message

Return Type:
  tuple of (bool, str)

Up

## createDevice

createDevice(microPythonWidget, deviceType, _vid, _pid, _boardName, _serialNumber)

Function to instantiate a MicroPython device object.

microPythonWidget (MicroPythonWidget)
  reference to the main MicroPython widget
deviceType (str)
  device type assigned to this device interface
_vid (int)
  vendor ID (unused)
_pid (int)
  product ID (unused)
_boardName (str)
  name of the board (unused)
_serialNumber (str)
  serial number of the board (unused)

Return:
  reference to the instantiated device object

Return Type:
  EspDevice

Up

## eraseFlash

eraseFlash(port, parent=None)

Slot to erase the device flash memory.

port (str)
  name of the serial port device to be used
parent (QWidget)
  reference to the parent widget (defaults to None)

Up

## flashAddonFirmware

flashAddonFirmware(port, parent=None)

Slot to flash some additional firmware images.

port (str)
  name of the serial port device to be used
parent (QWidget)
  reference to the parent widget (defaults to None)

Up

## flashPythonFirmware

flashPythonFirmware(port, parent=None)

Slot to flash a MicroPython firmware to the device.

port (str)
  name of the serial port device to be used
parent (QWidget)
  reference to the parent widget (defaults to None)

Up